Ficha técnica

Alcances necesarios

El token para consumir la API de Protest de Cobrança debe generarse utilizando el Authorization Code.

Es necesario incluir los siguientes alcances:

Alcance	Descripción
`brn:btg:empresas:banking:collections`	Permite programar, consultar y cancelar protestos
`brn:btg:empresas:banking:collections.read-only`	Permite solo consultar protestos y obtener documentos

Las operaciones de escritura (POST, DELETE) requieren el alcance collections. Las operaciones de lectura (GET) aceptan ambos alcances.

Protest de Cobrança — Descripción General de la API

La API de Protest de Cobrança de BTG Empresas permite que su empresa inicie un protesto notarial contra un deudor que no liquidó un boleto después del vencimiento. El protesto es un acto público que registra formalmente el incumplimiento y puede impactar el historial crediticio del deudor.

El flujo está organizado en torno a un único concepto central: el protesto (registro vinculado a una cobranza específica). Antes de programar un protesto, la cobranza debe estar vencida y en un estado elegible.

📘 Restricción de tipo

Protest es compatible exclusivamente con cobranzas del tipo BANKSLIP. Pix, QR Code y tarjeta de crédito no son compatibles.

Flujo de Protestos

Programar Protesto

La programación de un protesto es el punto de entrada del flujo. Se indica el collectionId de la cobranza vencida y la API registra el protesto para su envío al notario.

Solicitud — POST /{companyId}/banking/protest

{
  "collectionId": "0436436c-77a3-45c7-94af-527cb4dc80e2"
}

La cobranza referenciada debe ser del tipo BANKSLIP y estar en un estado que permita el protesto. El envío al notario ocurre de forma asíncrona después de la programación.

Respuesta — 201 Created

{
  "id": "9b3f1a2e-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "collectionId": "0436436c-77a3-45c7-94af-527cb4dc80e2",
  "status": "SCHEDULED",
  "issueDate": "2026-08-05",
  "collectionDueDate": "2026-07-15",
  "collectionIssueDate": "2026-07-01",
  "origin": "DEVELOPERS",
  "creditor": {
    "name": "Empresa XYZ Ltda",
    "fantasyName": "XYZ Pagamentos",
    "taxId": "37297902000141",
    "personType": "PJ",
    "address": {
      "state": "SP",
      "city": "São Paulo",
      "street": "Av. Brigadeiro Faria Lima",
      "zipCode": "04538-132",
      "number": "3477"
    }
  },
  "debtor": {
    "name": "João da Silva",
    "taxId": "12345678901",
    "personType": "PF",
    "email": "joao@email.com",
    "phoneNumber": "5511999999999",
    "address": {
      "state": "SP",
      "city": "São Paulo",
      "street": "Rua Exemplo",
      "zipCode": "01310-100",
      "number": "100"
    }
  },
  "documents": {
    "isCancellationDocumentAvailable": false,
    "isProtestDocumentAvailable": false
  },
  "createdAt": "2026-07-28T10:00:00.000Z",
  "updatedAt": "2026-07-28T10:00:00.000Z"
}

Guarde el campo id retornado — es el protestId y se utilizará en todas las operaciones posteriores: consulta, cancelación y obtención de documento.

Consultar Protesto

Una vez programado, es posible consultar el estado del protesto en cualquier momento utilizando el protestId.

Respuesta — GET /{companyId}/banking/protest/{id}

{
  "id": "9b3f1a2e-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "collectionId": "0436436c-77a3-45c7-94af-527cb4dc80e2",
  "status": "CONFIRMED",
  "issueDate": "2026-08-05",
  "collectionDueDate": "2026-07-15",
  "collectionIssueDate": "2026-07-01",
  "origin": "DEVELOPERS",
  "creditor": { "..." : "..." },
  "debtor": { "..." : "..." },
  "documents": {
    "isCancellationDocumentAvailable": false,
    "isProtestDocumentAvailable": true
  },
  "createdAt": "2026-07-28T10:00:00.000Z",
  "updatedAt": "2026-07-28T12:30:00.000Z"
}

El campo documents.isProtestDocumentAvailable indica cuándo el documento notarial está listo para descarga. El documento de cancelación (isCancellationDocumentAvailable) solo está disponible después de que el notario confirme la cancelación.

Obtener Documento de Protesto

El documento es generado por el notario y está disponible solo después de que el protesto alcance el estado CONFIRMED (para el documento de protesto) o después de que se confirme la cancelación (para el documento de cancelación).

Solicitud — GET /{companyId}/banking/protest/{id}/document?type=PROTEST

El parámetro type acepta dos valores:

Valor	Descripción
`PROTEST`	Documento notarial del protesto
`CANCELLATION`	Documento notarial de la cancelación

Respuesta — 200 OK

{
  "base64": "JVBERi0xLjQKMSAwIG9iago8PC..."
}

Decodifique el campo base64 para obtener el PDF del documento.

📘 Disponibilidad del documento

Consultar el documento antes de que esté disponible retorna 404. Verifique documents.isProtestDocumentAvailable (o isCancellationDocumentAvailable) en la respuesta del GET /{companyId}/banking/protest/{id} antes de intentar la descarga.

Cancelar Protesto (individual)

Cancela un protesto individualmente de forma síncrona. El protesto debe estar en un estado que permita la cancelación (SCHEDULED o PROCESSING).

Solicitud — DELETE /{companyId}/banking/protest/{id}?feesResponsible=PAYEE

El parámetro de consulta feesResponsible es opcional:

Valor	Descripción
`PAYER`	Costos notariales cobrados al deudor
`PAYEE`	Costos notariales cobrados al acreedor (su empresa)

Respuesta — 204 No Content

Sin cuerpo de respuesta. Para verificar el estado actualizado, consulte el protesto mediante GET /{companyId}/banking/protest/{id}.

Operaciones en Lote

Las operaciones en lote se procesan de forma asíncrona — la API retorna 202 Accepted inmediatamente y procesa cada elemento individualmente. Utilice el endpoint individual GET /{companyId}/banking/protest/{id} para monitorear el estado de cada protesto.

Programar Protestos en Lote

Solicitud — POST /{companyId}/banking/protest/batch

{
  "collectionIds": [
    "0436436c-77a3-45c7-94af-527cb4dc80e2",
    "1e5d83c8-92b5-4f39-827c-8c3d45a2b9f1"
  ]
}

Respuesta — 202 Accepted

Sin cuerpo de respuesta.

Cancelar Protestos en Lote

Solicitud — DELETE /{companyId}/banking/protest/batch

{
  "protests": [
    {
      "protestId": "9b3f1a2e-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "feesResponsible": "PAYEE"
    }
  ]
}

El campo feesResponsible por elemento es opcional. Cuando se omite, no se define ningún responsable de costos para ese protesto.

Respuesta — 202 Accepted

Sin cuerpo de respuesta.

Máquina de estados del Protesto

El protesto recorre los siguientes estados a lo largo de su ciclo de vida:

Status	Descripción
`CANCELED`	Protesto cancelado antes de ser enviado al notario
`FAILED`	Falla en el envío al notario
`PAID`	Deuda pagada después de la confirmación del protesto
`SETTLED`	Protesto dado de baja/liquidado
`FORFEITED`	Protesto expirado sin pago
`REMOVE_FAILED`	Falla en la eliminación del protesto
`REMOVED`	Protesto eliminado con éxito

Referencia de IDs

ID	Tipo	Creado por	Usado por
`protestId`	`UUID`	`POST /banking/protest`	`GET /banking/protest/{id}`, `GET /banking/protest/{id}/document`, `DELETE /banking/protest/{id}`, lote de cancelación
`collectionId`	`UUID`	Collections API	`POST /banking/protest` (entrada), `POST /banking/protest/batch` (entrada)

Operaciones individuales vs. en lote

Operación	Endpoint	Respuesta
Programar	`POST /{companyId}/banking/protest`	`201 Created` + `ProtestResponse` completo
Consultar	`GET /{companyId}/banking/protest/{id}`	`200 OK` + `ProtestResponse` completo
Cancelar	`DELETE /{companyId}/banking/protest/{id}`	`204 No Content`
Obtener documento	`GET /{companyId}/banking/protest/{id}/document?type=PROTEST`	`200 OK` + `{ base64: "..." }`
Programar en lote	`POST /{companyId}/banking/protest/batch`	`202 Accepted`
Cancelar en lote	`DELETE /{companyId}/banking/protest/batch`	`202 Accepted`

Alcances necesarios​

Protest de Cobrança — Descripción General de la API

Flujo de Protestos​

Programar Protesto​

Consultar Protesto​

Obtener Documento de Protesto​

Cancelar Protesto (individual)​

Operaciones en Lote​

Programar Protestos en Lote​

Cancelar Protestos en Lote​

Máquina de estados del Protesto​

Referencia de IDs​

Operaciones individuales vs. en lote​